توزیع بسته‌های پایتون: انتشار در PyPI و مدیریت نسخه

اکوسیستم گسترده پایتون توسط مجموعه عظیمی از بسته‌ها قدرت گرفته است که به راحتی از طریق فهرست بسته‌های پایتون (PyPI) در دسترس هستند. این راهنما یک نمای کلی و جامع از نحوه توزیع بسته‌های پایتون خودتان از طریق PyPI ارائه می‌دهد و اطمینان می‌دهد که برای توسعه‌دهندگان در سراسر جهان قابل دسترس باشند. ما ابزارهای ضروری، بهترین شیوه‌ها برای مدیریت نسخه و گردش‌کارها برای ایجاد و انتشار بسته‌های پایتون با کیفیت بالا را بررسی خواهیم کرد.

چرا بسته پایتون خود را توزیع کنیم؟

توزیع بسته پایتون شما مزایای متعددی دارد:

• اشتراک‌گذاری کار شما: به توسعه‌دهندگان دیگر اجازه می‌دهد تا به راحتی از کد شما استفاده مجدد کنند و همکاری و نوآوری را تقویت می‌کند. تصور کنید یک تیم جهانی از ابزارهای تخصصی تحلیل داده شما که با پایتون ساخته شده، استفاده می‌کند.
• مدیریت وابستگی‌ها: فرآیند مدیریت وابستگی‌ها در پروژه‌های دیگر را ساده می‌کند. بسته شما می‌تواند با یک دستور واحد، همراه با تمام وابستگی‌هایش، نصب شود.
• مشارکت در متن‌باز: به شما امکان می‌دهد در جامعه متن‌باز مشارکت کنید و برای کار خود شناخته شوید. بسیاری از اجزای حیاتی نرم‌افزار، بسته‌های متن‌بازی هستند که توسط توسعه‌دهندگان در سراسر جهان نگهداری می‌شوند.
• کنترل نسخه و به‌روزرسانی‌ها: روشی ساختاریافته برای مدیریت نسخه‌ها، انتشار به‌روزرسانی‌ها و رفع اشکالات فراهم می‌کند. این امر تضمین می‌کند که کاربران همیشه به جدیدترین و قابل اعتمادترین نسخه بسته شما دسترسی دارند.
• نصب آسان: نصب را برای کاربران از طریق `pip install your-package-name` ساده می‌کند.

ابزارهای ضروری برای توزیع بسته پایتون

چندین ابزار برای ایجاد و توزیع بسته‌های پایتون ضروری هستند:

• setuptools: کتابخانه‌ای پرکاربرد برای تعریف فراداده‌های بسته، شامل نام، نسخه، وابستگی‌ها و نقاط ورود. این ابزار استاندارد بالفعل برای بسته‌بندی پروژه‌های پایتون است.
• wheel: یک فرمت توزیع که فرآیند نصب کارآمدتر و قابل اعتمادتری نسبت به توزیع‌های منبع (source distributions) فراهم می‌کند. Wheelها توزیع‌های از پیش ساخته‌شده‌ای هستند که بدون نیاز به کامپایل قابل نصب هستند.
• twine: ابزاری برای آپلود امن بسته شما به PyPI. Twine اطلاعات کاربری و داده‌های بسته شما را در حین انتقال رمزگذاری می‌کند و از شنود و حملات مرد میانی (man-in-the-middle) محافظت می‌کند.
• venv/virtualenv: اینها ابزارهایی برای ایجاد محیط‌های ایزوله پایتون هستند. استفاده از محیط‌های مجازی برای مدیریت وابستگی‌ها و جلوگیری از تداخل بین پروژه‌های مختلف بسیار حیاتی است.

راه‌اندازی پروژه شما

قبل از اینکه بتوانید بسته خود را توزیع کنید، باید پروژه خود را به درستی ساختاربندی کنید.

نمونه ساختار پروژه

my_package/
├── my_package/
│   ├── __init__.py
│   ├── module1.py
│   └── module2.py
├── tests/
│   ├── __init__.py
│   ├── test_module1.py
│   └── test_module2.py
├── README.md
├── LICENSE
├── setup.py
└── .gitignore

توضیح:

• my_package/: دایرکتوری اصلی حاوی کد منبع بسته شما.
• my_package/__init__.py: دایرکتوری `my_package` را به یک بسته پایتون تبدیل می‌کند. این فایل می‌تواند خالی باشد یا حاوی کد اولیه باشد.
• my_package/module1.py, my_package/module2.py: ماژول‌های پایتون شما که حاوی کد واقعی هستند.
• tests/: دایرکتوری حاوی تست‌های واحد شما. نوشتن تست برای اطمینان از کیفیت و قابلیت اطمینان بسته شما بسیار مهم است.
• README.md: یک فایل Markdown که توضیحات بسته، دستورالعمل‌های استفاده و سایر اطلاعات مرتبط را ارائه می‌دهد. این اغلب اولین چیزی است که کاربران در PyPI می‌بینند.
• LICENSE: فایلی حاوی مجوزی که بسته شما تحت آن توزیع می‌شود (مانند MIT, Apache 2.0, GPL). انتخاب مجوز مناسب برای مشخص کردن نحوه استفاده دیگران از کد شما ضروری است.
• setup.py: فایل پیکربندی اصلی که فراداده‌های بسته و دستورالعمل‌های ساخت آن را تعریف می‌کند.
• .gitignore: فایل‌ها و دایرکتوری‌هایی را که باید توسط Git نادیده گرفته شوند (مانند فایل‌های موقت، مصنوعات ساخت) مشخص می‌کند.

ایجاد فایل `setup.py`

فایل `setup.py` قلب توزیع بسته شماست. این فایل حاوی فراداده‌هایی درباره بسته شما و دستورالعمل‌هایی برای ساخت و نصب آن است. در اینجا یک نمونه آورده شده است:

import setuptools

with open("README.md", "r") as fh:
    long_description = fh.read()

setuptools.setup(
    name="my_package",  # با نام بسته خود جایگزین کنید
    version="0.1.0",
    author="Your Name",  # با نام خود جایگزین کنید
    author_email="your.email@example.com", # با ایمیل خود جایگزین کنید
    description="یک بسته نمونه کوچک",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/yourusername/my_package", # با URL مخزن خود جایگزین کنید
    packages=setuptools.find_packages(),
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    python_requires='>=3.6',
    install_requires=[
        "requests", # وابستگی نمونه
    ],
)

توضیح:

• name: نام بسته شما که در PyPI استفاده خواهد شد. یک نام منحصر به فرد و توصیفی انتخاب کنید.
• version: شماره نسخه بسته شما. از نسخه‌بندی معنایی (semantic versioning) پیروی کنید (پایین را ببینید).
• author, author_email: نام و آدرس ایمیل شما.
• description: توضیح کوتاهی از بسته شما.
• long_description: توضیحی طولانی‌تر و با جزئیات بیشتر که معمولاً از فایل `README.md` شما خوانده می‌شود.
• long_description_content_type: فرمت توضیحات طولانی شما را مشخص می‌کند (مثلاً "text/markdown").
• url: آدرس URL صفحه اصلی بسته شما (مثلاً مخزن GitHub).
• packages: لیستی از بسته‌ها برای گنجاندن در توزیع شما. `setuptools.find_packages()` به طور خودکار تمام بسته‌های پروژه شما را پیدا می‌کند.
• classifiers: فراداده‌هایی که به کاربران کمک می‌کند بسته شما را در PyPI پیدا کنند. طبقه‌بندی‌های مناسب را از لیست طبقه‌بندی‌های Trove انتخاب کنید. در نظر بگیرید که طبقه‌بندی‌هایی برای نسخه‌های پشتیبانی‌شده پایتون، سیستم‌عامل‌ها و مجوزها را شامل شود.
• python_requires: حداقل نسخه پایتون مورد نیاز برای استفاده از بسته شما را مشخص می‌کند.
• install_requires: لیستی از وابستگی‌هایی که بسته شما به آنها نیاز دارد. این وابستگی‌ها هنگام نصب بسته شما به طور خودکار نصب می‌شوند.

مدیریت نسخه: نسخه‌بندی معنایی

نسخه‌بندی معنایی (SemVer) یک طرح نسخه‌بندی پرکاربرد است که روشی واضح و سازگار برای اطلاع‌رسانی ماهیت تغییرات در بسته شما فراهم می‌کند.

یک شماره نسخه SemVer از سه بخش تشکیل شده است: MAJOR.MINOR.PATCH.

• MAJOR (اصلی): زمانی افزایش می‌یابد که تغییرات API ناسازگار ایجاد می‌کنید. این نشان‌دهنده یک تغییر قابل توجه است که ممکن است کاربران را ملزم به به‌روزرسانی کد خود کند.
• MINOR (فرعی): زمانی افزایش می‌یابد که قابلیتی را به صورت سازگار با نسخه‌های قبلی اضافه می‌کنید. این نشان‌دهنده ویژگی‌ها یا بهبودهای جدیدی است که کد موجود را خراب نمی‌کند.
• PATCH (اصلاحی): زمانی افزایش می‌یابد که اصلاحات باگ سازگار با نسخه‌های قبلی را انجام می‌دهید. این برای اصلاحات کوچکی است که ویژگی‌های جدیدی اضافه نمی‌کنند یا عملکرد موجود را مختل نمی‌کنند.

مثال‌ها:

• 1.0.0: انتشار اولیه.
• 1.1.0: یک ویژگی جدید بدون شکستن کد موجود اضافه شده است.
• 1.0.1: یک باگ در نسخه 1.0.0 برطرف شده است.
• 2.0.0: تغییرات API ناسازگار ایجاد شده است.

استفاده از SemVer به کاربران کمک می‌کند تا تأثیر ارتقاء به نسخه جدید بسته شما را درک کنند.

ساخت بسته شما

هنگامی که فایل `setup.py` خود را پیکربندی کردید، می‌توانید بسته خود را بسازید.

1. ایجاد یک محیط مجازی: بسیار توصیه می‌شود که یک محیط مجازی برای ایزوله کردن وابستگی‌های بسته خود ایجاد کنید. از `python3 -m venv .venv` (یا `virtualenv .venv`) استفاده کنید و سپس آن را فعال کنید (`source .venv/bin/activate` در لینوکس/macOS، `.venv\Scripts\activate` در ویندوز).
2. نصب وابستگی‌های ساخت: دستور `pip install --upgrade setuptools wheel` را اجرا کنید.
3. ساخت بسته: دستور `python setup.py sdist bdist_wheel` را اجرا کنید. این دستور دو فایل توزیع در دایرکتوری `dist` ایجاد می‌کند: یک توزیع منبع (sdist) و یک توزیع wheel (bdist_wheel).

فایل `sdist` حاوی کد منبع و فایل `setup.py` شماست. فایل `bdist_wheel` یک توزیع از پیش ساخته‌شده است که می‌تواند سریع‌تر نصب شود.

انتشار بسته شما در PyPI

قبل از اینکه بتوانید بسته خود را منتشر کنید، باید یک حساب کاربری در PyPI (https://pypi.org/) ایجاد کرده و یک توکن API بسازید. این توکن برای احراز هویت آپلودهای شما استفاده خواهد شد.

1. ثبت‌نام در PyPI: به https://pypi.org/account/register/ بروید و یک حساب کاربری ایجاد کنید.
2. ایجاد یک توکن API: به https://pypi.org/manage/account/ بروید، به بخش "API tokens" پایین بروید و یک توکن جدید ایجاد کنید. این توکن را به صورت امن ذخیره کنید، زیرا برای آپلود بسته خود به آن نیاز خواهید داشت.
3. نصب Twine: دستور `pip install twine` را اجرا کنید.
4. آپلود بسته شما: دستور `twine upload dist/*` را اجرا کنید. از شما نام کاربری (__token__) و رمز عبور (توکن API که ایجاد کردید) خواسته می‌شود.

نکته مهم امنیتی: هرگز توکن API خود را در مخزن خود commit نکنید. آن را به صورت امن ذخیره کنید و از متغیرهای محیطی یا روش‌های امن دیگر برای دسترسی به آن در طول فرآیند آپلود استفاده کنید.

تست نصب بسته شما

پس از انتشار بسته، ضروری است که تست کنید آیا به درستی نصب می‌شود یا خیر.

1. ایجاد یک محیط مجازی جدید: این کار تضمین می‌کند که شما نصب را در یک محیط تمیز تست می‌کنید.
2. نصب بسته شما: دستور `pip install your-package-name` را اجرا کنید.
3. وارد کردن و استفاده از بسته شما: در یک مفسر پایتون، بسته خود را وارد کرده و تأیید کنید که همانطور که انتظار می‌رود کار می‌کند.

یکپارچه‌سازی مداوم و استقرار مداوم (CI/CD)

برای خودکارسازی فرآیند ساخت، تست و انتشار بسته خود، می‌توانید از ابزارهای CI/CD مانند GitHub Actions، GitLab CI یا Travis CI استفاده کنید.

در اینجا نمونه‌ای از یک گردش‌کار GitHub Actions آمده است که بسته شما را ساخته و در PyPI منتشر می‌کند:

name: انتشار در PyPI

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Set up Python 3.x
      uses: actions/setup-python@v2
      with:
        python-version: 3.x
    - name: نصب وابستگی‌ها
      run: |
        python -m pip install --upgrade pip
        pip install setuptools wheel twine
    - name: ساخت بسته
      run: python setup.py sdist bdist_wheel
    - name: انتشار بسته در PyPI
      run: |
        twine upload dist/* \
          -u __token__ \
          -p ${{ secrets.PYPI_API_TOKEN }}

توضیح:

• این گردش‌کار زمانی فعال می‌شود که یک نسخه جدید در GitHub منتشر شود.
• این گردش‌کار کد را checkout می‌کند، پایتون را راه‌اندازی می‌کند، وابستگی‌ها را نصب می‌کند، بسته را می‌سازد و آن را در PyPI آپلود می‌کند.
• secrets.PYPI_API_TOKEN یک secret در GitHub است که توکن API PyPI شما را ذخیره می‌کند. شما باید این secret را در تنظیمات مخزن GitHub خود پیکربندی کنید.

بهترین شیوه‌ها برای توزیع بسته پایتون

• نوشتن مستندات جامع: یک فایل `README.md` با جزئیات و همچنین مستندات API با استفاده از ابزارهایی مانند Sphinx را شامل کنید. مستندات واضح و کامل برای آسان کردن استفاده از بسته شما حیاتی است.
• نوشتن تست‌های واحد: کد خود را به طور کامل تست کنید تا از کیفیت و قابلیت اطمینان آن اطمینان حاصل کنید. از یک فریم‌ورک تست مانند pytest یا unittest استفاده کنید.
• پیروی از راهنمای سبک PEP 8: به راهنمای سبک پروپوزال بهبود پایتون 8 (PEP 8) پایبند باشید تا کدی سازگار و خوانا داشته باشید.
• استفاده از یک مجوز: یک مجوز متن‌باز مناسب برای مشخص کردن نحوه استفاده دیگران از کد خود انتخاب کنید.
• وابستگی‌های خود را به‌روز نگه دارید: به طور منظم وابستگی‌های بسته خود را به‌روز کنید تا از رفع باگ‌ها، وصله‌های امنیتی و ویژگی‌های جدید بهره‌مند شوید.
• استفاده از یک محیط مجازی: همیشه بسته خود را در یک محیط مجازی توسعه داده و تست کنید تا وابستگی‌ها را ایزوله کنید.
• بین‌المللی‌سازی (i18n) و محلی‌سازی (l10n) را در نظر بگیرید: اگر بسته شما با متن یا داده‌های رو به کاربر سروکار دارد، آن را برای انطباق با زبان‌ها و مناطق مختلف آماده کنید. این کار پایگاه کاربران بالقوه شما را در سطح جهانی گسترش می‌دهد. ابزارهایی مانند Babel می‌توانند در این زمینه کمک کنند.
• مدیریت مناطق زمانی و ارزهای مختلف: اگر بسته شما با تاریخ‌ها، زمان‌ها یا تراکنش‌های مالی سروکار دارد، به مناطق زمانی و ارزهای مختلف در سراسر جهان توجه داشته باشید. از کتابخانه‌ها و APIهای مناسب برای مدیریت صحیح این پیچیدگی‌ها استفاده کنید.
• ارائه پیام‌های خطای واضح: پیام‌های خطای آموزنده‌ای بنویسید که به کاربران کمک کند بفهمند چه چیزی اشتباه رفته و چگونه آن را برطرف کنند. در صورت امکان این پیام‌های خطا را به زبان‌های مختلف ترجمه کنید.
• به دسترسی‌پذیری فکر کنید: هنگام طراحی رابط کاربری و مستندات بسته خود، کاربران دارای معلولیت را در نظر بگیرید. از دستورالعمل‌های دسترسی‌پذیری پیروی کنید تا اطمینان حاصل شود که بسته شما برای همه قابل استفاده است.

مباحث پیشرفته

• بسته‌های فضای نام (Namespace packages): به شما امکان می‌دهد یک بسته پایتون را در چندین دایرکتوری یا حتی چندین توزیع تقسیم کنید.
• نقاط ورود (Entry points): به شما امکان می‌دهد توابع یا کلاس‌هایی را تعریف کنید که از بسته‌های دیگر یا از خط فرمان قابل فراخوانی باشند.
• فایل‌های داده (Data files): به شما امکان می‌دهد فایل‌های غیر پایتونی (مانند فایل‌های داده، فایل‌های پیکربندی) را در توزیع خود بگنجانید.
• وابستگی‌های شرطی (Conditional dependencies): به شما امکان می‌دهد وابستگی‌هایی را مشخص کنید که فقط تحت شرایط خاصی (مثلاً در یک سیستم‌عامل خاص) مورد نیاز هستند.

نتیجه‌گیری

توزیع بسته پایتون شما در PyPI راهی عالی برای به اشتراک گذاشتن کار خود با جهان و مشارکت در اکوسیستم پایتون است. با پیروی از مراحل و بهترین شیوه‌های ذکر شده در این راهنما، می‌توانید بسته‌های پایتون با کیفیتی ایجاد و منتشر کنید که نصب، استفاده و نگهداری آنها آسان باشد. به یاد داشته باشید که برای اطمینان از موفقیت بسته خود، مستندات واضح، تست کامل و مدیریت نسخه سازگار را در اولویت قرار دهید.